R Training: 03 - Functions

1 Functions Introduction

1.1 Function Structure

One of the most useful parts of R programming is the ability to write custom functions. This gives the user the flexibility to automate any task that they need. To start, let’s open up one of the functions from the RUO package to see what’s going on:

APPLY.BND() # This function won't run
function (DATA, RBND, VARS = NULL, Uniq_Keys, USE_RED = FALSE,KEEP_DATA = TRUE) {}

The first thing we’ll notice is the word ‘function’ followed by a set of rounded brackets and finally some curly braces. Within the rounded brackets are the function’s ARGUMENTS and the curly braces contain the BODY of the function.

Creating a function is just like you would assign a value to a variable, except you now include the word “function”.

For example:

x <- 2
x <- function() {}

We have just created a function called x.

1.2 Function Arguments

Arguments provide a way for the user to control the variables within a function without having to modify the source code.

Let’s look at an example:

returnSum <- function(x, y) {
  return(x + y) # Return will be covered soon
}

Our example function has two arguments, x and y. We can tell returnSum that x and y are any numbers and it will give us back the sum of those two numbers.

returnSum(3, 5)

[1] 8

returnSum(7, 16)

[1] 23

returnSum(2, 8)

[1] 10

Without arguments, we would have to hard code x and y and then our functions wouldn’t be very useful.

returnSum <- function () {
  return(4)
}

returnSum()

[1] 4

Arguments don’t have to just be integers, they can be any data type, even other functions. The only restriction is that all operations within the function have to work on that data type.

Look back at our original example, APPLY.BND. Notice that some of the arguments are assigned values and some are not?

function (DATA, RBND, VARS = NULL, Uniq_Keys, USE_RED = FALSE,KEEP_DATA = TRUE)

The arguments with pre- assigned values are called ‘Default Arguments’. These behave just like regular arguments, except if you don’t assign them a value they will take on the default value (hence the name.)

returnSum <- function(x, y, z = 5) {
  return(x + y + z)
}

returnSum(2, 3)

[1] 10

Note, you can still assign any value to default arguments, it will overwrite the default.

returnSum(2, 3, 6)

[1] 11

You’ll typically use default arguments when you don’t expect the value of that variable to change often. The user won’t need to specify the argument everytime they call the function.

IMPORTANT

The order of the arguments matters if you’re not explicitly specifying them. Notice when we’ve been calling our functions, we haven’t been writing x = 2, y = 3, etc. This is because we’re sticking to the order in which they appear within the function definition.

#Look at what happens if we don't respect the order:
returnSum <- function(x, y = 5, z) {
  return(x + y + z)
}

returnSum(4, 6)
#This will not run

Will return: Error in returnSum(4, 6) : argument “z” is missing, with no default

Y has a default value, but because we haven’t specified assignments, 6 is being assigned to y (overwriting the default) and z is left undefined. To prevent this, explicitly specify your assignments:

returnSum(4, z = 6)

[1] 15

However since we specified that z=6, the code will run.

Good practice dictates that you should start making your assignments explicit after the second argument; which also means if you’re writing functions, don’t put default values for your first two arguments.

Let’s dive a bit more into the body of the function now. At their core, functions are a set of instructions performed on a set of variables to generate a desired outcome. We’ve just covered arguments, where you assign values to the set of variables, so logicaly the body is where we define the set of instructions.

1.3 EDA Function

Let’s refer to the EDA lesson and see if we can convert some parts into functions. A good rule of thumb is that if you’re repeating something 3 or more times, you can probably convert it into a function.

Let’s look at the Data Manipulation step of the EDA lesson. Specifically, this chunk of code:

AGG.VEH <- DATA_Scored %>%
  group_by(Clt_Insurer_Tx,
           Clt_Account_No, 
           Pol_Policy_No, 
           Veh_Id_No) %>%
  summarise(LC_Veh_Total = sum(LC_TOTAL))

AGG.INSURER <- DATA_Scored %>% 
  left_join(AGG.VEH) %>%
  filter(Clo_Sale_In == 1 & Dri_Type_Cd == 'P') %>% # To have the data by vehicle
  select(LC_Veh_Total,
         Prm_Trm_Veh_Tot_Am,
         Clt_Insurer_Tx) %>% 
  group_by(Clt_Insurer_Tx) %>% 
  summarise(Prm_Trm_Veh_Mean = mean(Prm_Trm_Veh_Tot_Am),
            LR_Veh_Mean  = sum(LC_Veh_Total, na.rm = TRUE)/sum(Prm_Trm_Veh_Tot_Am),
            Xpo_Veh_Nb   = sum(n()))

print(AGG.INSURER)

AGG.DRI_AGE <- DATA_Scored %>% 
  left_join(AGG.VEH) %>%
  filter(Clo_Sale_In == 1 & Dri_Type_Cd == 'P') %>% # To have the data by vehicle
  select(LC_Veh_Total,
         Prm_Trm_Veh_Tot_Am,
         Dri_Marital_Status_In,
         Dri_Age_Nb) %>% 
  group_by(Dri_Marital_Status_In,
           Dri_Age_Nb) %>% 
  summarise(Prm_Trm_Veh_Mean = mean(Prm_Trm_Veh_Tot_Am),
            LR_Veh_Mean  = sum(LC_Veh_Total, na.rm = TRUE)/sum(Prm_Trm_Veh_Tot_Am),
            Xpo_Veh_Nb   = sum(n()))

head(AGG.DRI_AGE)

Function for Loss Ratios by Vehicle

Assuming we’re interested in being able to look at our loss ratios by driver but want to be able to conduct the analysis multiple times, we would need our data, variables and driver type to be flexible, so we thus include these as arguments in our funciton.

aggregateVars <- function(DATA, KEEP.VARS, GROUP.VARS, DRIVER.TYPE = 'P') {
  
  # It doesn't matter what you call your data within the function, 
  # I like to use temp
  temp <- DATA %>% 
    left_join(AGG.VEH) %>%
    filter(Clo_Sale_In == 1 & Dri_Type_Cd == DRIVER.TYPE) %>% 
    select(LC_Veh_Total, # Required var
           Prm_Trm_Veh_Tot_Am, # Required var
           # one_of is a dplyr function designed to be used with Select
           one_of(KEEP.VARS)) %>% 
    # Notice we're using group_by_at instead of group_by now
    # Some dplyr functions have versions designed for functional 
    # programming; this is one.
    group_by_at(GROUP.VARS) %>% 
    summarize(Prm_Trm_Veh_Mean = mean(Prm_Trm_Veh_Tot_Am),
              LR_Veh_Mean  = sum(LC_Veh_Total, na.rm = TRUE)/sum(Prm_Trm_Veh_Tot_Am),
              Xpo_Veh_Nb   = sum(n()))
  
  # We'll cover return in a moment
  return(temp)
}

Now we can define our KEEP.VARS and GROUP.VARS We’re defining the column names as strings, R knows what to do though

KEEP.VARS <- c("Dri_Marital_Status_In", "Dri_Age_Nb")
GROUP.VARS <- KEEP.VARS 

And call our function

AGG.DRI_AGE_Function_Out <- aggregateVars(
  DATA = DATA_Scored, 
  KEEP.VARS, 
  GROUP.VARS = GROUP.VARS
  )

Notice that this outputs the exact same thing as the above chunk of code. The difference is, now we can perform the same analysis on different variables with minimal effort.

KEEP.VARS <- c("Dri_Gender_Cd", "Dri_Yrs_Licensed_AU_Nb")
GROUP.VARS <- KEEP.VARS 

AGG.Yrs_Lic_Function_Out <- aggregateVars(
  DATA_Scored, 
  KEEP.VARS, 
  GROUP.VARS = GROUP.VARS
)

Hopefully this example has demonstrated the flexibility and usefulness of creating custom functions. The key-takeaway is that if you can script it, you can turn it into a function for re-useability.

1.4 Variable Scope

Variable scope is a pretty complex topic, but for most use cases in our job knowing the basics is sufficient. The easiest way to explain variable scope is with an example.

Observe

y <- 7

demoFunction <- function(x) {

  print(paste("The value of x is ", x, " and the value of Y is ", y), sep = "")
  
}

demoFunction(8)

[1] "The value of x is  8  and the value of Y is  7"

rm(y) # To delete y

We can see that even though y is not defined within the function, demoFunction is still able to find the y value that was declared outside of the function. This is because of variable scope. By default, the user is working in something called the Global Environment and functions will have access to the variables declared in our global environment. Now if we want to look at another example:

y <- 6
demoFunction2 <- function() {
  y <- 4
  y
}

demoFunction2()

[1] 4

We can see that the function assigns y a value of 4 within the function and will return this value of y which is 4.

y

[1] 6

However, when we look at y outside of the function y is still 6. This again has to do with the environment and the fact that assigning y the value of 4 within the function will not change the value of y in the global environment.

1.5 Variable Returns

We mentioned above through our most recent example that enviornments do not pass all their objects onto the global environment. So how do you get objects from a child environment to its parent?

The answer is with the return function. When you call a function, it is going to return something at the end of its run. It may create many objects along the way, but at its end it will only return one object ( that object can be a list of many objects.) The return function is your way of telling function what you want them to return.

returnValue <- function(x, y) {
  
  z <- x * y
  
  return(z)
}

returnValue(2, 5)

[1] 10

It is not entirely necessary to use use return() in functions. If there is no return specified, your function will return the last thing it calls internally.

returnValue <- function(x, y) {
  
  z <- x * y
  
  z
}

returnValue(2, 5)

[1] 10

The above function will work just fine and will return z, just as we want. Using return() is only recommended because it helps with comprehension of your code. If you’re writing functions which will be used by users other than yourself, it is a good idea to include return() calls.

Finally, because functions are returning a single object, you need to make sure you’re storing that object in your global environment if you intend to use it later.

w <- returnValue(2, 5) # Store the output object from returnValue in a variable called w
p <- w*3

p

[1] 30

2 Examples

We’ve been able to see some functions and have determined that they are useful for resuability of code and performing tasks. We want to continue this mind set and see how some simple code can be saved to tackle problems that will be faced multiple times.

2.1 Bivariate Analysis

2.1.1 Explanation

Let us see a simple example of a function that will perform an initial bivariate analysis of our data set. We want something flexible that will allow us to perform analysis regardless of our data set and response variable.

The arguments for this function include:

1. DATA: The data that we will be using. exp: DATA = DATA_QUO_AUTO

2. x: The name of the x varaible. exp: x = Dri_Age_Nb

3. y: The name of the y variable. Examples such as loss cost or closing, exp: y = Clo_Sale_In

These functions below will combine what has been seen so far to provide some examples of easy to use functions.

2.1.2 Breakdown of Function Example

This function example here provides users with the ability to see how a response variable such as closing is different across a variable of our choice. We will keep y as a default variable of Clo_Sale_In but as previously mentioned the y argment can be changed if needed.

Don’t worry too much about !! and enquo, but this is simply a technique we can use to pass the name of the data frame variable without using quotations "".

summaryStats <- function(DATA,x,y = Clo_Sale_In){
  DATA %>%
    group_by(!! enquo(x)) %>%
    summarize(Mean = mean(!!enquo(y), na.rm=TRUE),
              Count = n())
}

summaryStats(DATA_QUO_AUTO,Clt_Home_Main_Location_Cd)

summaryStats(DATA_QUO_AUTO,Clt_Segment)

summaryStats(DATA_QUO_AUTO,Veh_Model_Yr_Dt,Clo_Sale_In)

2.2 Plotting

We will use the plotting function plotly as seen in previous examples that will allow us to have a flexible function for y vs x plotting. We can created the grouped data in the exact same was as previously before we plot it

plotlyData <- function(DATA,x,y = Clo_Sale_In) {

Grouped_Data = DATA %>%
  group_by(!!enquo(x)) %>%
  summarize(Response_Mean = mean(!!enquo(y), na.rm=TRUE),
            Count = n())
p <- plot_ly(data = Grouped_Data) %>%
  #add_lines will provide the mean response at each group
  add_lines(
    x =  enquo(x),
    y =~ Response_Mean,
    name ="Observed Mean"
  ) %>% 
  add_bars(
    x =  enquo(x),
    y =~  Count,
    yaxis = "y2",
    opacity = 0.35,
    name = "Exposure"
  ) %>%
  layout(
    title = paste0(enexpr(y), " vs ", enexpr(x)),
    xaxis = list(title = paste0(enexpr(x))),
    yaxis = list(title = paste0(enexpr(y)), side = "left", overlaying = "y2"),
    barmode = "stack",
    yaxis2 = list(title = "Exposure", side = "right")
  )
return(p)
}

We can now try out our plot function to have plots generated and saved in respective variables.

Plot_Dri_Age_Nb <- plotlyData(DATA_QUO_AUTO,Dri_Age_Nb)
Plot_Clt_Home_Main_Location_Cd<-plotlyData(DATA_QUO_AUTO,Clt_Home_Main_Location_Cd)
Plot_Dri_Ubi_In <- plotlyData(DATA_QUO_AUTO,Dri_Ubi_In)

And we can now look at these plots.

Plot_Dri_Age_Nb

Plot_Clt_Home_Main_Location_Cd

Plot_Dri_Ubi_In

These are 3 examples of functions that you could create yourself. From the use of other functions and previously written code, you could create functions tailored to your everyday needs.

Finally we want to try to export these plots.

#Change this to a path that works for you to export to
setwd("C:/Users/opti1407/OneDrive - The Toronto-Dominion Bank/Documents")

htmlwidgets::saveWidget(Plot_Dri_Age_Nb, "Plot_Dri_Age_Nb.html")
htmlwidgets::saveWidget(Plot_Clt_Home_Main_Location_Cd, "Plot_Clt_Home_Main_Location_Cd.html")
htmlwidgets::saveWidget(Plot_Dri_Ubi_In, "Plot_Dri_Ubi_In.html")

In summary once we’ve written code whether it be for rebasing, scoring or quickly analysing our data, we can convert this code into a function to allow us to use it for a variety of problems.